Fetch Company Details API

This document outlines the details of the Company Details API.

API Description

Objective

The Fetch Company Details API provides comprehensive company information from the Ministry of Corporate Affairs (MCA) database. It retrieves detailed company profiles, including registration details, financial information, compliance status, and director information, making it ideal for corporate verification and due diligence processes.

Input	Output
The Corporate Identification Number (CIN)	Details about: Company profile and status Financial information Registration details Director information The complete list of output fields is available in the Success Response Details section

did you know

The Corporate Identification Number (CIN) is a unique 21-character alphanumeric code that contains information about a company's registration details, including state, year of incorporation, and registration number.

API URL

https://ind-engine.thomas.hyperverge.co/v1/fetchCompanyDetails

API Endpoint

fetchCompanyDetails

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should send all data in JSON format through a POST request.

Authentication

You need a unique pair of application ID ( appId ) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

API Request Details

Method - `POST`

Headers

Parameter	Mandatory or Optional	Description	Valid Values
`content-type`	Mandatory	This parameter defines the media type for the request payload.	application/json
`appId`	Mandatory	The application ID shared by HyperVerge	Not Applicable - this is a unique value
`appKey`	Mandatory	The application key shared by HyperVerge	Not Applicable - this is a unique value
`transactionId`	Mandatory	The unique ID for the customer journey.	Not Applicable - this is a unique value related to a transaction in your application

Input

The following table provides the details of the parameter required for the API's request body:

Parameter	Mandatory or Optional	Description	Allowed Values	Default Value
`cin`	Mandatory	The CIN	A 21-character alphanumeric code	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the API:

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/fetchCompanyDetails' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "cin": "<Enter_the_CIN>"
}'

Success Response

The following code snippet demonstrates a success response from the API:

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "numberOfMembers": "",
    "subCategory": "<Subcategory_Of_The_Company>",
    "class": "<Class_Of_The_Company>",
    "companyType": "<Type_Of_The_Company>",
    "companyName": "<Name_Of_The_Company>",
    "paidUpCapital": "<Paid_Up_Capital>",
    "authorisedCapital": "<Authorised_Capital>",
    "whetherListed": "<Whether_The_Company_Is_Listed>",
    "dateOfIncorporation": "<Date_Of_Incorporation_In_MM/DD/YYYY_Format>",
    "lastAgmDate": "<Date_Of_Last_AGM_In_MM/DD/YYYY_Format>",
    "registrationNumber": "<Registration_Number>",
    "registeredAddress": "<Registered_Address_Of_The_Company>",
    "activeCompliance": "",
    "suspendedAtStockExchange": "",
    "balanceSheetDate": "<Balance_Sheet_Date_In_MM/DD/YYYY_Format>",
    "category": "<Category_Of_The_Company>",
    "status": "<Operational_Status_Of_The_Company>",
    "cin": "<Corporate_Identification_Number>",
    "rocOffice": "<ROC_Office_Name>",
    "countryOfIncorporation": "<Country_Of_Incorporation>",
    "descriptionOfMainDivision": "",
    "addressOtherThanRegisteredOffice": "<Alternate_Office_Address>",
    "emailID": "<Official_Email_ID>",
    "splitAddress": {
      "district": "<District>",
      "state": "<State>",
      "city": "<City>",
      "pincode": "<Pincode>",
      "country": "<Country>",
      "addressLine": "<Address_Line>"
    },
    "natureOfBusiness": "",
    "noOfDirectors": <Number_Of_Directors>,
    "statusForEfiling": "",
    "statusUnderCirp": "",
    "pan": "",
    "directorDetails": [
      {
        "din": "<Director_Identification_Number>",
        "designation": "<Designation_Of_The_Director>",
        "dateOfAppointment": "<Date_Of_Appointment_In_MM/DD/YYYY_Format>",
        "address": "<Address_Of_The_Director>",
        "name": "<Name_Of_The_Director>",
        "whetherDscRegistered": "",
        "dscExpiryDate": "",
        "pan": "<Masked_PAN_Of_The_Director>",
        "noOfCompanies": <Number_Of_Companies_Director_Associated_With>,
        "fatherName": "<Name_Of_The_Director's_Father>",
        "dob": "<Date_Of_Birth_Of_The_Director_In_MM/DD/YYYY_Format>",
        "splitAddress": {
          "district": "<District>",
          "state": "<State>",
          "city": "<City>",
          "pincode": "<Pincode>",
          "country": "<Country>",
          "addressLine": "<Address_Line>"
        }
      }
    ]
  },
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Success Response Details

The following table outlines the details of the success response from the API:

Parameter	Type	Description
status	string	The status of the API request indicating success or failure
statusCode	integer	The HTTP status code returned for the API request
result	object	The main response object containing all company-related information
CompanyMasterSummary	object	Contains comprehensive company registration and operational details
LastUpdatedDateTime	string	The timestamp of the last data update in DD-MM-YYYY format
CompanyCin	string	The 21-character Corporate Identification Number of the company
CompanyName	string	The registered legal name of the company
CompanyDateOfInc	string	The date of company incorporation in DD-MM-YYYY format
CompanyRocCity	string	The Registrar of Companies office location for the company
CompanyRegNumber	string	The unique registration number assigned by the Registrar of Companies
CompanyCategory	string	The legal category of the company (e.g., Company limited by shares)
CompanySubCategory	string	The sub-category classification of the company (e.g., Indian Non-Government Company)
CompanyClass	string	The class of the company (e.g., Public Company, Private Company)
CompanyAuthCapital	string	The total authorized capital of the company in Indian Rupees
CompanyPaidUpCapital	string	The total paid-up capital of the company in Indian Rupees
CompanyFullAddress	string	The complete registered office address of the company
CompanyRegState	string	The state where the company is registered
CompanyRegCity	string	The city where the company is registered
CompanyRegPinCode	string	The PIN code of the company's registered address
CompanyBookAddress	string	The address where the company maintains its books of accounts
CompanyMcaStatus	string	The current status of the company as per MCA records (e.g., Active, Inactive)
CompanyLastAgmDate	string	The date of the last Annual General Meeting in DD-MM-YYYY format
CompanyLastBsDate	string	The date of the last Balance Sheet filing in DD-MM-YYYY format
CompanyEmail	string	The official email address of the company
CompanyWebSite	string	The official website URL of the company
CompanyMcaIndustry	string	The primary industry classification of the company as per MCA
CompanyMcaIndustryDivision	string	The specific industry division classification as per MCA
CompanyMcaIndustryGroup	string	The industry group classification as per MCA
StatusUnderCIRP	string	The status of the company under Corporate Insolvency Resolution Process
DirectorSignatoryMasterBasic	object	Contains information about current and past directors and signatories of the company
ChargesMasterBasic	object	Contains information about charges and liabilities registered against the company
metaData	object	Contains metadata information about the API request
requestId	string	The unique identifier for the API request
transactionId	string	The transaction ID associated with the API request

Error Responses

Invalid CIN Length
Invalid CIN Format
Invalid Credentials
Record Not Found
Invalid Authentication Key

{
  "message": "Input Validation Error: does not meet minimum length of 21",
  "statusCode": 400,
  "status": "failure"
}

{
  "message": "Input Validation Error: XSS validation failed for cin",
  "statusCode": 400,
  "status": "failure"
}

{
  "message": "Missing/Invalid credentials",
  "statusCode": 401,
  "status": "failure"
}

{
  "status": "failure",
  "statusCode": 404,
  "error": "No Record Found",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

{
  "status": "failure",
  "statusCode": 401,
  "error": "Authkey is invalid",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Error Response Details

A failure or error response from the module contains a failure status, with a relevant status code and error message.
The following table lists all error responses.

Status Code	Error Message	Error Description
400	Input Validation Error: does not meet minimum length of 21	The provided CIN is either empty or has less than 21 characters
400	Input Validation Error: XSS validation failed for cin	The provided CIN contains invalid characters or format
401	Missing/Invalid credentials	The request is either missing the mandatory `appId` and `appKey` combination or has invalid values
401	Authkey is invalid	The provided authentication key is invalid or expired
404	No Record Found	The provided CIN exists but no matching record was found in the database
500	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution

API Description​

Objective​

API URL​

API Endpoint​

Overview​

Authentication​

API Request Details

Method - POST

Headers

Input​

Request​

Success Response​

Success Response Details​

Error Responses​

Error Response Details​